home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1997 September / Macworld (1997-09).dmg / Shareware World / Utilities / Text Processing / Alpha / Help / ElectricAlias Help < prev    next >
Text File  |  1994-06-16  |  9KB  |  286 lines
  1. ######### electricAlias Help LAST UPDATE: 01/24/93 9:29:39 AM #########
  2.  
  3. This help file refers to version 1.7 of electricAlias.tcl
  4.  
  5. QUICK START
  6.  
  7.     'electricAlias' is a general-purpose Tcl package that provides a 
  8.     flexible way to automate entering repetitive text. This text can be as 
  9.     simple as the current date, or can be a template containing many entry 
  10.     points where additional data is added. In this case, 'electricAlias' 
  11.     inserts the boilerplate and provides a convenient way to jump between 
  12.     entry points. Using electricAlias is as simple as typing a key word and 
  13.     hitting the tab key. 
  14.  
  15.     The following instructions will get you up and running ASAP. You will have 
  16.     three new bindings: 1. <TAB> will be bound to 'electricAlias-insert' and 2. 
  17.     <control-j> will be bound to 'nextStop', which jumps you to the next entry 
  18.     point in the current aliased text. 3. <control-shift-j> is bound to 
  19.     'prevStop', which jumps you to the previous entry point. 
  20.  
  21.     $HOME:Tcl:ElectricAlias:Aliases contains default aliases for many modes.
  22.     You can modify these or create your own.
  23.  
  24.     To invoke in the current session invoke it from the Utils menu or call 
  25.     'loadElectricAliases' from you userStartup.tcl file.
  26.  
  27.     Now go read about TEMPLATES below and examine the aliases files
  28.     to understand how it all fits together.
  29.  
  30. GENERAL USAGE
  31.  
  32.     ElectricAlias is simple to use.  Normally it is bound to the
  33.     <TAB> character, so you just type away.  You define aliases
  34.     in the alias definitions files $HOME:Tcl:ElectricAlias:aliases:aliases*.
  35.  
  36. PROCEDURE SYNTAX
  37.  
  38.     electricAlias-insert
  39.  
  40.             Invokes alias template insertion.  Text is scanned from
  41.             the current cursor position to the beginning of the line.
  42.             If the non-whitespace text immediately adjacent has an
  43.             alias entry, then template insertion proceeds.
  44.  
  45.     electricAlias-idefine
  46.  
  47.             An interactive mode to define aliases.  Crude.
  48.  
  49.     electricAlias-def MODE NAME ?DEFINITION?
  50.  
  51.             Defines or displays an alias template.  If DEFINITION
  52.             is omitted and the alias exists, then the current
  53.             definition is returned per TCL 'return'.
  54.             
  55.             Aliases may have embedded variables, TCL commands, stops,
  56.             line-ends and deletes as described under TEMPLATES below.
  57.  
  58.             If MODE begins with a bullet (•), then the alias is only effective
  59.             when used as the first token on a line.
  60.  
  61.     electricAlias-undefine MODE NAME
  62.  
  63.             Undefines entry for alias MODE and NAME
  64.  
  65.     electricAlias-exists MODE NAME
  66.  
  67.             Returns 1 if alias NAME exists; otherwise 0.
  68.  
  69.     electricAlias-list ?MODE?
  70.  
  71.             Inserts a sorted list of current definitions.
  72.             Specifying a MODE will restrict the returned list to
  73.             that mode.
  74.  
  75.             List may be used in another TCL.  Uses getalias
  76.             proc.
  77.  
  78.     electricAlias-mode ?NAME?
  79.  
  80.             Sets the current alias mode.  This is used to determine
  81.             which alias to use in a given situation.  Leading bullet (•),
  82.             if any, is removed.  This forces use of the MODE field when
  83.             defining aliases that must occur as the first token of a line.
  84.             
  85.             If the NAME is missing, then the current mode is returned.
  86.  
  87.     electricAlias-names ?MODE?
  88.  
  89.             Returns a list of currently defined alias names.
  90.             Specifying a MODE will restrict the returned list to
  91.             that mode.
  92.  
  93.     electricAlias-off
  94.  
  95.             Turns electricAlias off
  96.  
  97.     electricAlias-on
  98.  
  99.             Turns electricAlias on
  100.  
  101.     electricAlias-iundefine
  102.  
  103.             An interactive mode to remove aliases.  Crude.
  104.  
  105.     electricAlias-removeall ?MODE?
  106.  
  107.             Removes all alias definitions and variables
  108.             Specifying a MODE will restrict the returned list to
  109.             that mode.
  110.  
  111.     electricAlias-var MODE NAME ?DEFINITION?
  112.  
  113.             Defines an alias variable for use in templates.  If the pattern
  114.             §{NAME} is found during template insertion, it is replaced with
  115.             the DEFINITION.  This allows a single template to have multiple
  116.             uses.
  117.             
  118.             If the DEFINITION is omitted, then the current definition
  119.             is returned.
  120.  
  121.     electricAlias-version
  122.     
  123.             Returns the current version info.
  124.  
  125. TEMPLATE DEFINITIONS
  126.  
  127.     Templates provide a mechanism for inserting text with temporary stops.
  128.     Facility is also provided to preserve indentation and allow for alias
  129.     variable insertion and TCL commands.  This is accomplished with special
  130.     character sequences embedded within the template.  Hopefully, none of
  131.     these are needed in the inserted text itself.  Here are the definitions:
  132.  
  133.     \b        deletes one character to the left.  Useful for outdenting.
  134.  
  135.     •        inserts a temporary mark
  136.  
  137.     §«CMD»    inserts the results of executing the TCL command CMD.  Be
  138.             careful if your command contains anything that would be
  139.             construed as part of a regular expression.  To be safe use
  140.             only single procedures with simple arguments.  Also, the CMD
  141.             may not contain a closing '»'.
  142.  
  143.             It is possible for §«CMD»'s to be recursive (subject to the same
  144.             restrictions above) or include §{VAR}'s.
  145.  
  146.     §{VAR}    inserts an alias variable (IMPORTANT: inserted AFTER §«CMD»'s)
  147.  
  148.             It is possible for §{VAR}'s to be recursive or include §«CMD»'s
  149.             (subject to the §«CMD» restrictions above).
  150.  
  151.     \r        inserts a new-line break and cues procedure to preserve indentation
  152.             if alias mode is bullet type or when called explicitly.
  153.  
  154.     \n        identical to \r
  155.  
  156.     \t        inserts a tab for indentation
  157.  
  158.     Other escapes are as defined by TCL
  159.  
  160.     You can trick templates to insert some of the above with the following;
  161.     although, why you would want to is beyond me.
  162.     
  163.     '\ \bb' inserts literal '\b'
  164.     '§ \b«CMD»' inserts literal '§«CMD»'
  165.     '§ \b{VAR}' inserts literal '§{VAR}'
  166.  
  167. SIMPLE EXAMPLES
  168.  
  169.     The following examples show several templates that might be appropriate
  170.     for the C programming language:
  171.     
  172.     electricAlias-def •C while   "while (•) {\r\t•\r}/*endwhile*/•"
  173.     electricAlias-def •C for     "for (•;•;•) {\r\t•\r}/*endfor*/•"
  174.     electricAlias-def •C if      "if (•) {\r\t•\r}/*endif*/•"
  175.     electricAlias-def •C elseif  "\b} else if (•) {\r•"
  176.     electricAlias-def •C else    "\b} else {\r•"
  177.  
  178.     Suppose that the user has an open window for MYFILE.C (please bear
  179.     with the poor graphics):
  180.     +-------------------
  181.     | MYFILE.C
  182.     +-------------------
  183.     |
  184.     +-------------------
  185.  
  186.     By typing 'while\t' this would insert:
  187.     
  188.     +-------------------
  189.     | MYFILE.C
  190.     +-------------------
  191.     |while () {
  192.     |    
  193.     |}/*endwhile*/
  194.     +-------------------
  195.     
  196.     The cursor would be positioned inside the parentheses ready for an
  197.     expression to be typed.  When done with the expression, the user would
  198.     press CONTROL-J to jump to the next position where the body of the
  199.     WHILE loop would be entered.  A final CONTROL-J would position the user
  200.     just after the /*endwhile*/ comment.
  201.     
  202.     For this example, suppose the user types 'i < 5';
  203.  
  204.     Suppose the user type 'if\t' inside the body of the while, then we
  205.     would get:
  206.  
  207.     +-------------------
  208.     | MYFILE.C
  209.     +-------------------
  210.     |while (i < 5) {
  211.     |    if () {
  212.     |        
  213.     |    }/*endif*/
  214.     |}/*endwhile*/
  215.     +-------------------
  216.  
  217.     For the IF conditional suppose the user typed '*c != 0'.
  218.     Now in the body of the IF the user enters 'a = 1;else\ta = 2' and gets:
  219.     
  220.     +-------------------
  221.     | MYFILE.C
  222.     +-------------------
  223.     |while (i < 5) {
  224.     |    if (*c != 0) {
  225.     |        a = 1;
  226.     |    } else {
  227.     |        a = 2;
  228.     |    }/*endif*/
  229.     |}/*endwhile*/
  230.     +-------------------
  231.  
  232.     Suppose you don't like my indentation style for C.  Perhaps the following
  233.     definitions and the resulting code would be more suited to your tastes:
  234.  
  235.     electricAlias-def •C while   "while (•)\r  {\r\t•\r  }\r•"
  236.     electricAlias-def •C for     "for (•;•;•)\r  {\r    •\r  }\r•"
  237.     electricAlias-def •C if      "if (•)\r  {\r    •\r  }\r•"
  238.     electricAlias-def •C elseif  "\b\b}\r\b\b\b\belse if (•)\r\b\b{\r•"
  239.     electricAlias-def •C else    "\b\b}\r\b\b\b\belse\r\b\b{\r•"
  240.  
  241.     Now MYFILE.C would look like this:
  242.     
  243.     +-------------------
  244.     | MYFILE.C
  245.     +-------------------
  246.     |while (i < 5)
  247.     |  {
  248.     |    if (*c != 0)
  249.     |      {
  250.     |        a = 1;
  251.     |      }
  252.     |    else
  253.     |      {
  254.     |        a = 2;
  255.     |      }
  256.     |   
  257.     |  }
  258.     +-------------------
  259.  
  260.  
  261.  
  262. COPYRIGHT
  263.  
  264.     Copyright © 1993 by David C. Black
  265.     All rights reserved.
  266.  
  267.     Redistribution and use in source and binary forms are permitted
  268.     provided that the above copyright notice and this paragraph are
  269.     duplicated in all such forms and that any documentation,
  270.     advertising materials, and other materials related to such
  271.     distribution and use acknowledge that the software was developed
  272.     by David C. Black.
  273.  
  274.     THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
  275.     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  276.     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  277.  
  278. AUTHOR
  279.     
  280.     David C. Black
  281.     Internet: black@mpd.tandem.com
  282.     GEnie:    D.C.BLACK
  283.     USnail:   6217 John Chisum Lane, Austin, Tx 78749-1838
  284.  
  285. THE END
  286.